local-serverless-stack 0.5.0 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,82 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-07-10
+
+The self engine: an in-process AWS emulator that replaces LocalStack for the typical serverless dev loop — DynamoDB, SQS, S3, EventBridge, SNS (minimal), Lambda control plane and STS served by the orchestrator itself on one port. No Docker, no container, no auth token; boots in milliseconds; data persisted in local files. Opt-in (`engine: "self"` / `lss start --self-engine`) — LocalStack mode remains the default and fully supported. Design: `docs/PRD_SELF_ENGINE.md`; coverage matrix: `docs/SELF_ENGINE.md`.
+
+### Added
+- **Engine selection**: `engine: "localstack" | "self"` and a `selfEngine` config block (`port` default 14566 — deliberately outside the 4566–4599 range a real LocalStack intercepts on some hosts —, `dataDir`, `account`, `idleUnloadMs`, `memoryBudgetMb`, `fsync`, `fallbackEndpoint`); env overrides `LSS_ENGINE`/`LSS_ENGINE_PORT`; CLI `lss start --self-engine` (rejected when combined with the LocalStack-only `--external`/`--pro`/`--localstack-token`).
+- **AWS wire front door** (`src/server/engine/http/`): one `node:http` listener routing by SigV4 credential scope → `X-Amz-Target` → path heuristics; per-protocol error serialization (JSON `__type`, Query XML, S3 XML with body-less HEAD errors, Lambda REST + `x-amzn-ErrorType`); the `x-amzn-query-error` SQS compat header; `aws-chunked` request decoding (SDK v3 streaming PutObject); `x-amzn-RequestId` on every response; `/_localstack/health` alias so existing readiness polls keep working; `selfEngine.fallbackEndpoint` reverse-proxies any unimplemented service/operation verbatim to a LocalStack during migration — unsupported calls otherwise fail loudly, never silently succeed.
+- **File-backed store** (`src/server/engine/store/`): JSONL snapshot + append-only WAL per data table (torn-tail-safe replay, seq-based compaction), atomic JSON catalogs for metadata, content-addressed blob storage for S3 bodies (never held in the heap); registration writes metadata only — data hydrates on first touch (streamed line-by-line) and dehydrates after `idleUnloadMs` or under the `memoryBudgetMb` LRU budget; debounced flushes (20 ms / 256 KB) with opt-in fsync.
+- **DynamoDB emulator** with a hand-rolled expression engine (KeyCondition/Condition/Filter/Update/Projection: comparators, `BETWEEN`/`IN`, boolean precedence, document paths, `SET`/`REMOVE`/`ADD`/`DELETE` with exact decimal-string `N` arithmetic), GSI/LSI queries with projection and sparse-index semantics, `Limit`-before-filter parity, `LastEvaluatedKey` paging (including index LEKs), lazy TTL (filtered at read, purged at compaction with Service-identity stream REMOVEs), stream records (`INSERT`/`MODIFY`/`REMOVE` per `StreamViewType`), batch ops, and the full `DescribeTable` introspection shape (`LatestStreamArn` present immediately).
+- **SQS emulator**: FIFO (per-group ordering, 5-minute dedup window), event-driven long polling (parked promises — no polling loops), visibility-timeout redelivery, live `ApproximateNumberOfMessages*` counters (QueueInspector `await-idle`/metrics work unchanged), `MD5OfMessageBody`/`MD5OfMessageAttributes`, CreateQueue idempotent-success on identical attributes; messages are memory-only with a graceful-shutdown snapshot under `persistence`.
+- **S3 emulator**: byte-exact object round trips, `Range` reads, `ListObjectsV2` (prefix/delimiter/CommonPrefixes/continuation/`encoding-type=url`), `DeleteObjects`, `CopyObject`, versioning flag, notification configuration (including the legacy `CloudFunctionConfiguration` XML names), quoted-MD5 ETags, `GetBucketLocation` us-east-1 quirk; multipart answers an explicit `NotImplemented` until the hardening phase.
+- **EventBridge emulator**: buses, rules with validated patterns (exact, array-OR, `prefix`, `exists`, nested keys; unsupported operators rejected at `PutRule` with `InvalidEventPatternException`), targets, `PutEvents` with per-entry results, plus minimal **SNS** (topics + logged `Publish`) and **STS** (`GetCallerIdentity`).
+- **Lambda control plane**: the provisioner's proxy functions are absorbed as metadata (zip discarded, `INVOKE_URL` kept — it doubles as the HTTP fallback for services still on serverless-offline), event source mappings with UUIDs persisted across restarts, `UpdateEventSourceMapping Enabled` = QueueInspector hold/release, `Invoke` honoring `X-Amz-Invocation-Type`.
+- **In-process event dispatch** (`src/server/engine/dispatch/`): SQS delivery loops (batch size + `MaximumBatchingWindowInSeconds`, failure → visibility redelivery, capped backoff on runtime-unavailable), DynamoDB stream tailers (`TRIM_HORIZON`/`LATEST`, retry-then-advance with the `DDBStreamBatchInfo` OnFailure SQS envelope), S3 notification fan-out (event globs + prefix/suffix filters, `eventVersion 2.1` records), EventBridge target invocation (`Input`/`InputPath`) and **schedule triggering** (`rate()` + 6-field AWS cron, single timer wheel) — all delivered straight into the LSS Lambda runtime: no proxy Lambdas, no HTTP hop, no polling containers. Closes the long-standing scheduled-triggers TODO for self-engine mode.
+- **Example `examples/self-engine-sample`**: three microservices (orders → billing → notifications) exercising DynamoDB + SQS (cross-service ESM by ARN) + S3 + EventBridge on the self engine, registered with `sls package` only. Measured: engine boot ~10 ms; the full pipeline across the three services completes in ~170 ms — no Docker.
+- **Docs**: `docs/SELF_ENGINE.md` (coverage matrix, storage model, known divergences), `docs/PRD_SELF_ENGINE.md` (design), FEATURES.md §13, CONFIGURATION.md and README (self engine as the headline feature).
+- **VS Code tasks** (`.vscode/tasks.json`, now versioned via a `.gitignore` exception): build/dev, unit/coverage/integration tests, lint, cross-project typecheck, a `validate: pre-prod` sequence (lint → typecheck → tests → build), and one-click flows for the self-engine and eventbridge examples (start/register/drive pipeline/stop).
+
+### Changed
+- **Dashboard component library updated**: `@treeui/vue` `^0.6.1` → `^0.10.0` (latest). No API changes required in the LSS components — `vue-tsc` and the Vite build pass unchanged.
+- **Engine seam**: the LocalStack container lifecycle moved to `src/server/engine/backends/localstack-backend.ts`; `services/localstack-manager.ts` is now a thin facade over the new `EngineManager`, so the provisioner/explorers/seeds keep their imports and work against whichever engine is active (they always speak AWS SDK to `getConfig().endpoint`). Self-engine code is loaded via dynamic `import()` — LocalStack-mode memory footprint is unchanged.
+- `lambdaRuntime.invokeHost` defaults to `127.0.0.1` in self-engine mode (nothing runs inside Docker); explicit config still wins.
+- `GET /api/health` now includes an `engine: {kind, running, endpoint, ...}` block; the `localstack` boolean stays truthy when the active engine is healthy (client/UI compatibility).
+- The root package version is now `0.8.0`. The `serverless-lss` plugin package was not changed.
+
+### Fixed
+- **Branch-coverage gate restored to 100%**: closed the six uncovered branches left by the 0.7.0 EventBridge work (`cloudformation-parser.ts` — bus/rule with no `Properties`, rule with no `Targets`; `resource-provisioner.ts` — non-Error rejections in the event-rule pass and eventbus cleanup, `AddPermission` conflict/message-less fallbacks while wiring rule targets). `npm run test:coverage` passes again.
+
+### Tests
+- ~700 new unit tests (1802 total, up from 1100): wire router/SigV4/aws-chunked, store WAL/compaction/hydration/LRU-budget, DynamoDB expression engine (223 assertions) + emulator core, SQS/S3/EventBridge/SNS/STS/lambda-ctl emulators, dispatcher loops/stream tailers/scheduler, self-backend boot; engine selection covered in `config-manager` and `cli` suites. End-to-end smoke with real AWS SDK v3 clients against a booted engine (CRUD/Query/GSI, queue lifecycle, binary S3 round trip, per-entry PutEvents, ESM hold, restart persistence).
+
+## [0.7.0] - 2026-07-10
+
+EventBridge support: LSS can now provision the shared event bus and rule→Lambda triggers that previously required the last remaining `serverless deploy` (CloudFormation) step in local monorepo setups.
+
+### Added
+- **`AWS::Events::EventBus` provisioning**: buses declared in the `resources:` section are created in LocalStack on registration (idempotent — re-registration tolerates an existing bus). `PutEvents` from handlers already worked via the SDK; the bus just had to exist.
+- **`AWS::Events::Rule` triggers**: rules (event pattern or schedule, `ENABLED`/`DISABLED` state honored) are created on the declared bus and their Lambda targets wired through the same proxy model used by streams/SQS — EventBridge → proxy Lambda in LocalStack → LSS invoke API (130xx). Target `Input`/`InputPath` pass through; the bus is resolved from the template's logical ids, a literal name, or an ARN. Rules whose `EventBusName` can't be resolved from the template (e.g. `Fn::ImportValue`) are skipped with a warning instead of silently landing on the default bus.
+- **Resources-only stacks**: a registered service that declares only `resources:` (no functions, no ports) provisions its resources without starting a runtime worker, gateway listeners or watcher — this already worked structurally since 0.5.0 gated those on declared functions/ports, and is now covered by tests for the EventBus-only infra-stack case.
+- **Cleanup parity**: unregistering a service removes rule targets and rules first, then deletes its event buses.
+- **Dashboard visibility**: EventBridge buses and rules show up in the service detail page (own sections) and as counters in the services list (`resourceBreakdown.buses`/`eventRules`), so a resources-only infra stack no longer renders as "N total" with an empty body.
+- **Example `examples/eventbridge-sample`**: resources-only `events-stack` owning the shared bus (+ skipped Archive), a producer publishing `UserSignedUp` via `PutEvents`, and a consumer with an `events: eventBridge` trigger storing events in DynamoDB — registered with `sls package` only, no deploy. Its LocalStack runs on port `14566`, outside the standard 4566–4599 range, so a real LocalStack publishing that range (docker-compose defaults) can't intercept the example's `localhost` traffic on Docker Desktop/WSL2.
+
+### Fixed
+- **EventBridge event shape through proxies**: the generated LocalStack proxy Lambda no longer wraps EventBridge events in a `Records` array — handlers receive `source`/`detail-type`/`detail` at the top level, exactly like on AWS. SQS/DynamoDB/SNS batches keep their `Records` shape. Proxies created by earlier versions keep the old code until recreated (only their `INVOKE_URL` is updated in place); delete the proxy function or reset LocalStack to pick up the fix.
+
+### Changed
+- `AWS::Events::Archive` resources are accepted and skipped with a registration warning: LocalStack mocks Archives (CloudFormation reports `CREATE_COMPLETE` but `ListArchives` stays empty), so provisioning one locally would only fake success.
+- `CloudFormationParser.parse()` accepts an optional warnings sink; the registrar forwards template-level warnings (like skipped Archives) to the registering client alongside state-file warnings.
+- New runtime dependency: `@aws-sdk/client-eventbridge`.
+
+### Tests
+- Parser coverage for `AWS::Events::EventBus`/`Rule`/`Archive` (bus name fallback, pattern/schedule/state, `Fn::ImportValue` flagging, literal-ARN targets, warning sink) and ResourceProvisioner coverage for bus creation, rule wiring (proxy reuse, permissions, default vs named vs literal bus), unresolvable-bus/unsupported-target skips, and cleanup ordering.
+
+## [0.6.0] - 2026-07-09
+
+Corrections from integrating LSS 0.5.0 in a real monorepo using osls 4, serverless-esbuild ESM artifacts, HTTP API v2 authorizers, DynamoDB Streams, and Docker-in-Docker devcontainers.
+
+### Added
+- **Configurable LocalStack proxy callback host**: `lambdaRuntime.invokeHost` and `LSS_INVOKE_HOST` now control the host used when generated LocalStack Lambda proxies call back into LSS's invoke listener. The default remains `host.docker.internal`; devcontainers/DinD can point it at the Docker network gateway (for example `172.19.0.1`).
+- **Native TypeScript source loading when available**: in `source` mode, the runtime worker now tries Node's native TypeScript type stripping (`process.features.typescript`) before requiring `esbuild-register`, `tsx`, or `ts-node`.
+
+### Fixed
+- **Artifact resolution for osls/serverless package output**: `package.artifact` values such as `s7-identity.zip` are now resolved relative to `.serverless/` as well as the service root, and nonexistent declared candidates no longer suppress the `.serverless/*.zip` scan fallback.
+- **Stale LocalStack proxy `INVOKE_URL`**: re-registering a service now updates an existing proxy Lambda when the expected invoke URL changed (port renumbering or `invokeHost` changes).
+- **Service identity collisions**: service registration now uses the `service:` name from `serverless-state.json` instead of the directory basename, with migration for same-root legacy cache entries.
+- **Event source mapping fidelity**: CloudFormation `StartingPosition`, `MaximumRetryAttempts`, `FunctionResponseTypes`, `MaximumBatchingWindowInSeconds`, `FilterCriteria`, and `DestinationConfig.OnFailure` are parsed/applied where supported; duplicate checks compare the resolved live ARN instead of unresolved CFN refs.
+- **DynamoDB table fidelity**: `StreamViewType` is preserved and `TimeToLiveSpecification` is applied after table creation or on re-registration, including disabled TTL declarations.
+- **CLI stop/start race**: `lss stop` now waits for the orchestrator process to exit (with timeout) before returning, reducing immediate `lss start` failures from a still-bound port.
+
+### Changed
+- The root package version is now `0.6.0`. The `serverless-lss` plugin package was not changed.
+
+### Tests
+- Added/updated unit coverage for artifact resolution, Lambda runtime config env overrides, CloudFormation parsing, ResourceProvisioner proxy/TTL/event-source behavior, and the async CLI stop flow.
+
 ## [0.5.0] - 2026-07-08
 
 API Gateway & Lambda runtime emulation: LSS now registers every function and HTTP route a service declares, executes the handlers itself in per-service workers, and answers on the service's own API (30xx) and Lambda-invoke (130xx) ports — making `serverless-offline` optional. Monorepo callers and the LocalStack event proxies keep their ports and contracts unchanged; only the process answering changes.

package/README.md

@@ -2,16 +2,16 @@
 
 [![npm version](https://img.shields.io/npm/v/local-serverless-stack.svg)](https://www.npmjs.com/package/local-serverless-stack)
 
-**Local control plane for serverless development with LocalStack orchestration**
+**Local control plane for serverless development — with its own in-process AWS engine (no Docker) or LocalStack orchestration**
 
-LSS provides a unified local development environment for serverless microservices, eliminating the need to run separate LocalStack instances for each service.
+LSS provides a unified local development environment for serverless microservices: one orchestrator provisions and serves every AWS resource your services declare, eliminating the need to run separate LocalStack instances (or, with the **self engine**, any LocalStack at all).
 
 ## Features
 
-- **Centralized LocalStack**: Single LocalStack instance manages DynamoDB, SQS, SNS, S3, and Lambda
-- **Auto-provisioning**: Parses CloudFormation templates from `sls package` and provisions resources automatically
-- **Event source mappings**: Automatically connects SQS queues to Lambda handlers via LocalStack
-- **Lambda proxies**: Generated proxy functions forward events to serverless-offline invoke endpoints
+- **⚡ Self engine (the LSS differentiator)**: DynamoDB, SQS, S3, EventBridge, SNS and the Lambda control plane emulated **in-process** by the orchestrator — no Docker, no LocalStack, no auth token. Boots in milliseconds, stores data in local files, delivers events straight into your handlers. See [Self engine](#self-engine--no-docker-no-localstack-no-auth-token) below.
+- **Centralized provisioning**: Parses CloudFormation templates from `sls package` and provisions resources automatically — into the self engine or a single shared LocalStack, your choice per instance
+- **Event source mappings**: Automatically connects SQS queues, streams, S3 notifications and EventBridge rules to Lambda handlers
+- **Lambda runtime & API emulation**: LSS answers on the same API (30xx) and Lambda invoke (130xx) ports that serverless-offline used
 - **Web UI**: Vue 3 dashboard to monitor services, resources, and event mappings
 - **Hot reload**: Watch for code changes and auto-rebuild/reprovision
 - **Process management**: Start/stop microservices from the orchestrator
@@ -19,6 +19,57 @@ LSS provides a unified local development environment for serverless microservice
 
 See [docs/FEATURES.md](docs/FEATURES.md) for the complete feature inventory and how each capability is tested.
 
+## Self engine — no Docker, no LocalStack, no auth token
+
+LocalStack got heavy (a container eating 1 GB+ of RAM) and stopped being free by default
+(community images `>= 2026.5` require an auth token). The **self engine** replaces it for
+the typical serverless dev loop: the orchestrator itself serves the real AWS wire
+protocols on one port, so your application code, the AWS SDK, the dashboard and `lss seed`
+all work unchanged — there is simply no container underneath.
+
+```bash
+npx lss start --self-engine        # or "engine": "self" in lss.config.json
+```
+
+```
+AWS_ENDPOINT=http://localhost:14566   # point your services here, done
+```
+
+What you get:
+
+- **DynamoDB** with the full expression language (KeyCondition/Filter/Update/Projection,
+  exact decimal arithmetic), GSIs/LSIs, TTL and streams — items persisted in local
+  JSONL files under `~/.lss/engine/`, hydrated lazily and unloaded when idle.
+- **SQS** with FIFO, visibility redelivery and live counters; **S3** with byte-exact
+  object round trips and notifications; **EventBridge** with buses, pattern-filtered
+  rules and `rate()`/cron schedules; minimal **SNS** and **STS**.
+- **Events delivered in-process**: SQS batches, DynamoDB streams, S3 notifications and
+  EventBridge targets go straight from the engine to the LSS Lambda runtime — no proxy
+  Lambdas, no polling containers.
+
+```mermaid
+flowchart LR
+    APP[Your services<br/>AWS SDK → :14566] --> ENG
+    subgraph ORCH["One orchestrator process — no Docker"]
+        ENG[Self engine<br/>DynamoDB · SQS · S3<br/>EventBridge · SNS · STS]
+        ENG -->|in-process events| RT[LSS Lambda runtime<br/>your handlers, ports 30xx/130xx]
+        ENG --- FS[(local files<br/>~/.lss/engine)]
+    end
+```
+
+Measured on [examples/self-engine-sample](examples/self-engine-sample/) (3 microservices:
+orders → billing → notifications): engine boot **~10 ms**; a full pipeline crossing
+DynamoDB + SQS + S3 + EventBridge across the three services completes in **~170 ms** —
+with the whole stack being the orchestrator process plus one small worker per service.
+
+Migration is gradual: LocalStack mode remains the default and fully supported; a running
+instance picks one engine. Anything the self engine doesn't implement yet answers with an
+explicit error naming the operation — or is forwarded verbatim to a LocalStack via
+`selfEngine.fallbackEndpoint`. Coverage matrix and storage model:
+[docs/SELF_ENGINE.md](docs/SELF_ENGINE.md) · design/PRD:
+[docs/PRD_SELF_ENGINE.md](docs/PRD_SELF_ENGINE.md) · runnable demo:
+[examples/self-engine-sample](examples/self-engine-sample/).
+
 ## Architecture
 
 ```
@@ -41,18 +92,18 @@ local-serverless-stack/
 
 **Components**:
 - **CLI** (`bin/cli.js`): Background process management (start/stop/status/logs)
-- **Server** (`src/server/`): Express API + LocalStack orchestration
+- **Server** (`src/server/`): Express API + engine orchestration
+- **Engine** (`src/server/engine/`): the AWS provider behind everything — either the in-process **self engine** (port 14566, no Docker) or a managed/external **LocalStack** container (port 4566)
 - **UI** (`src/ui/`): Vue 3 dashboard for monitoring
 - **Plugin** (`packages/serverless-plugin/`): Auto-registration for Serverless Framework
-- **LocalStack**: Docker container (port 4566) with AWS services
 
 ## Quick Start
 
 ### Prerequisites
 
-- Node.js >= 18
-- Docker (for LocalStack)
+- Node.js >= 20
 - Serverless Framework 3.40.0
+- Docker — **only for the LocalStack engine**; the self engine (`--self-engine`) needs none
 
 ### Installation
 
@@ -86,9 +137,12 @@ See the [plugin documentation](packages/serverless-plugin/README.md) for configu
 LSS provides a simple CLI to manage the orchestrator in background mode:
 
 ```bash
-# Start the orchestrator in background
+# Start the orchestrator in background (managed LocalStack)
 npx lss start
 
+# Start with the in-process self engine instead — no Docker
+npx lss start --self-engine
+
 # Check if orchestrator is running
 npx lss status
 
@@ -105,6 +159,12 @@ npx lss help
 ### CLI Output
 
 ```bash
+$ npx lss start --self-engine
+🚀 LSS Orchestrator started (PID: 12345)
+📊 Server: http://localhost:3100
+🔧 Self Engine: http://localhost:14566 (no Docker)
+✅ Service is running
+
 $ npx lss start
 🚀 LSS Orchestrator started (PID: 12345)
 📊 Dashboard: http://localhost:3100
@@ -178,19 +238,19 @@ npx lss start
 cd your-microservice
 npx sls package
 
-# 3. Start serverless offline
-npx serverless offline start --host 0.0.0.0 --httpPort 3020 --lambdaPort 13020
-
-# 4. Monitor in the dashboard
+# 3. Monitor in the dashboard
 open http://localhost:3100
 ```
 
 Now when you send a message to an SQS queue in LocalStack, the orchestrator will:
 1. Detect the event via event source mapping
 2. Invoke the Lambda proxy in LocalStack
-3. Proxy forwards to serverless-offline on the invoke port
+3. Proxy calls LSS's Lambda invoke listener on the service invoke port
 4. Your handler executes
 
+If you still want serverless-offline to own the ports for a service, disable the
+LSS runtime globally or per service with `lambdaRuntime.enabled`/`serviceRuntime`.
+
 ## Project Structure
 
 ```
@@ -214,13 +274,30 @@ local-serverless-stack/
 ### Environment Variables
 
 - `PORT`: Orchestrator API port (default: 3100)
+- `LSS_ENGINE`: AWS engine — `localstack` (default) or `self` (in-process, no Docker)
+- `LSS_ENGINE_PORT`: Self engine port (default: 14566)
 - `ENABLE_DYNAMO_PROXY`: Enable DynamoDB proxy on port 8000 (default: false)
 - `DYNAMO_PROXY_PORT`: DynamoDB proxy port (default: 8000)
 
+### Engine selection
+
+```jsonc
+// lss.config.json
+{
+  "engine": "self",              // "localstack" (default) | "self"
+  "selfEngine": { "port": 14566 } // full reference: docs/SELF_ENGINE.md
+}
+```
+
+The self engine's default port sits **outside 4566–4599** on purpose: a real LocalStack
+install intercepts that whole range on some hosts (Docker Desktop/WSL2). `--self-engine`
+cannot be combined with the LocalStack-only flags (`--external`, `--pro`,
+`--localstack-token`).
+
 ### LocalStack Settings
 
 LocalStack is configured with:
-- Services: `dynamodb,sqs,sns,s3,lambda`
+- Services: `dynamodb,sqs,sns,s3,lambda,events`
 - Persistence: Enabled (volume: `lss-localstack-data`)
 - Lambda executor: `local` (no Docker-in-Docker required)
 - Docker socket: Mounted from host
@@ -479,6 +556,17 @@ sequenceDiagram
    - Response returned through proxy chain
    - Message deleted from queue on success, or sent to DLQ on failure
 
+> **Self-engine mode collapses this whole chain**: the engine's event source mapping
+> delivers the SQS batch **in-process** to the LSS Lambda runtime — no LocalStack
+> polling, no proxy Lambda, no HTTP hop:
+>
+> ```
+> LocalStack mode:  SQS → LocalStack ESM → proxy Lambda (container) → HTTP → handler
+> Self engine:      SQS (engine) → dispatcher → handler
+> ```
+>
+> The same applies to DynamoDB streams, S3 notifications and EventBridge targets.
+
 ## CLI Implementation Details
 
 The `npx lss` CLI is implemented in `/bin/cli.js` and provides:

package/bin/cli.js

@@ -96,6 +96,8 @@ function getConfig(config) {
     localstackImage: config.localstackImage,
     localstackAuthToken: config.localstackAuthToken,
     stateDir: config.stateDir,
+    engine: config.engine || 'localstack',
+    selfEnginePort: (config.selfEngine && config.selfEngine.port) || 14566,
   };
 }
 
@@ -150,7 +152,11 @@ function startOrchestrator() {
       const cfg = getConfig(config);
       console.log('✅ LSS Orchestrator already running (PID:', pid + ')');
       console.log(`📊 Server: http://localhost:${cfg.serverPort}`);
-      console.log(`🔧 LocalStack: http://localhost:${cfg.localstackPort}`);
+      if (cfg.engine === 'self') {
+        console.log(`🔧 Self Engine: http://localhost:${cfg.selfEnginePort}`);
+      } else {
+        console.log(`🔧 LocalStack: http://localhost:${cfg.localstackPort}`);
+      }
       if (cfg.enableDynamoProxy) {
         console.log(`🔄 DynamoDB Proxy: http://localhost:${cfg.dynamoProxyPort} (enabled)`);
       }
@@ -183,6 +189,13 @@ function startOrchestrator() {
   const useExternal = process.argv.includes('--external');
   const usePro = process.argv.includes('--pro');
   const cliToken = getArgValue('--localstack-token');
+  const useSelfEngine = process.argv.includes('--self-engine');
+
+  const engine = useSelfEngine ? 'self' : cfg.engine;
+  if (engine === 'self' && (useExternal || usePro || cliToken)) {
+    console.error('❌ --self-engine cannot be combined with --external, --pro or --localstack-token (those are LocalStack options).');
+    process.exit(1);
+  }
 
   const mode = useExternal ? 'external' : cfg.mode;
   const edition = usePro ? 'pro' : cfg.localstackEdition;
@@ -223,6 +236,9 @@ function startOrchestrator() {
   if (authToken) {
     env.LOCALSTACK_AUTH_TOKEN = authToken;
   }
+  if (engine === 'self') {
+    env.LSS_ENGINE = 'self';
+  }
   // Hand the same config file to the server so its ConfigManager reads the
   // identical serverPort/localstackPort/seedsDir/region/mode (not just the
   // hand-translated subset above). Keeps the two config loaders in agreement.
@@ -243,7 +259,11 @@ function startOrchestrator() {
 
   console.log('🚀 LSS Orchestrator started (PID:', child.pid + ')');
   console.log(`📊 Server: http://localhost:${cfg.serverPort}`);
-  console.log(`🔧 LocalStack: http://localhost:${cfg.localstackPort} (mode: ${mode}, edition: ${edition})`);
+  if (engine === 'self') {
+    console.log(`🔧 Self Engine: http://localhost:${cfg.selfEnginePort} (no Docker)`);
+  } else {
+    console.log(`🔧 LocalStack: http://localhost:${cfg.localstackPort} (mode: ${mode}, edition: ${edition})`);
+  }
   if (enableDynamoProxy) {
     console.log(`🔄 DynamoDB Proxy: http://localhost:${cfg.dynamoProxyPort} (enabled)`);
   }
@@ -262,7 +282,40 @@ function startOrchestrator() {
   }, 2000);
 }
 
-function stopOrchestrator() {
+// Poll kill(pid, 0) until the process is gone. SIGTERM alone isn't enough to
+// return from `stop`: an immediate `lss start` would race the dying orchestrator
+// for the server port and crash with EADDRINUSE.
+function waitForExit(pid, timeoutMs = 10000, intervalMs = 200) {
+  return new Promise(resolve => {
+    const deadline = Date.now() + timeoutMs;
+    let timer;
+    let done = false;
+    const finish = (value) => {
+      done = true;
+      if (timer) clearInterval(timer);
+      resolve(value);
+    };
+    const check = () => {
+      try {
+        process.kill(pid, 0);
+      } catch (e) {
+        finish(true);
+        return;
+      }
+      if (Date.now() >= deadline) {
+        finish(false);
+      }
+    };
+    // Fast path: the process is often already gone — check synchronously so
+    // `stop` resolves without ever scheduling (and leaking) an interval.
+    check();
+    if (!done) {
+      timer = setInterval(check, intervalMs);
+    }
+  });
+}
+
+async function stopOrchestrator() {
   const { pidFile } = runtimePaths();
   if (!fs.existsSync(pidFile)) {
     console.log('⚠️  LSS Orchestrator is not running');
@@ -273,13 +326,20 @@ function stopOrchestrator() {
 
   try {
     process.kill(pid, 'SIGTERM');
-    fs.unlinkSync(pidFile);
-    console.log('🛑 LSS Orchestrator stopped (PID:', pid + ')');
   } catch (e) {
     console.error('❌ Failed to stop process:', e.message);
     if (fs.existsSync(pidFile)) {
       fs.unlinkSync(pidFile);
     }
+    return;
+  }
+
+  const exited = await waitForExit(pid);
+  fs.unlinkSync(pidFile);
+  if (exited) {
+    console.log('🛑 LSS Orchestrator stopped (PID:', pid + ')');
+  } else {
+    console.warn(`⚠️  Process ${pid} did not exit within 10s of SIGTERM — the server port may still be busy. Check \`lss status\` before starting again.`);
   }
 }
 
@@ -598,6 +658,7 @@ Options:
                                Applies to start/stop/status/logs so an isolated instance
                                can be addressed without cd-ing into its folder.
   --enable-dynamo-proxy        Enable DynamoDB proxy on port 8000 (for start command)
+  --self-engine                Use the in-process AWS engine instead of LocalStack (no Docker)
   --external                   Connect to a LocalStack already running, do not spawn a container
   --pro                        Use the LocalStack Pro image (requires LOCALSTACK_AUTH_TOKEN)
   --localstack-token <token>   Pass a LOCALSTACK_AUTH_TOKEN to the container
@@ -637,6 +698,7 @@ Configuration:
 
 Examples:
   npx lss start                              # Start the orchestrator (managed LocalStack)
+  npx lss start --self-engine                # Use the in-process engine (no Docker, port 14566)
   npx lss start --enable-dynamo-proxy        # Start with DynamoDB proxy enabled
   npx lss start --external                   # Connect to an external LocalStack
   npx lss start --pro                        # Use LocalStack Pro (token required)
@@ -687,6 +749,7 @@ module.exports = {
   getArgValue,
   runtimePaths,
   getOrchestratorPath,
+  waitForExit,
   formatError,
   buildHttpError,
   firstPositional,

package/dist/server/engine/backends/localstack-backend.d.ts

@@ -0,0 +1,25 @@
+import type { EngineBackend } from '../engine-backend.js';
+export declare class LocalStackBackend implements EngineBackend {
+    readonly kind: "localstack";
+    private process;
+    private _isRunning;
+    private endpoint;
+    private readonly containerName;
+    private readonly configManager;
+    constructor();
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private waitForReady;
+    isRunning(): boolean;
+    getEndpoint(): string;
+    getConfig(): {
+        endpoint: string;
+        region: string;
+        credentials: {
+            accessKeyId: string;
+            secretAccessKey: string;
+        };
+    };
+    healthDetail(): Record<string, unknown>;
+}
+//# sourceMappingURL=localstack-backend.d.ts.map

package/dist/server/engine/backends/localstack-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localstack-backend.d.ts","sourceRoot":"","sources":["../../../../src/server/engine/backends/localstack-backend.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,qBAAa,iBAAkB,YAAW,aAAa;IACrD,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IACtC,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAS;IAKzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;;IASxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA+HtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAwBb,YAAY;IAmB1B,SAAS,IAAI,OAAO;IAIpB,WAAW,IAAI,MAAM;IAIrB,SAAS;;;;;;;;IAWT,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQxC"}